{ "openapi": "3.0.0", "info": { "title": "Suggestions", "description": "The **Marketplace API** enables marketplaces and sellers hosted on VTEX to perform their collaborative operations. \r\n\r\n>⚠️ The marketplace must [create an appKey and appToken](https://developers.vtex.com/docs/guides/getting-started-authentication) for each non-VTEX seller that will use this API.\r\n\r\n## Index\r\n\r\n### Notification\r\n\r\nEndpoints used by sellers to notify marketplaces that the price or inventory language has changed for one of their SKUs.\r\n\r\n`POST` [Notify marketplace of price update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price)\r\n\r\n`POST` [Notify marketplace of inventory update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory)\r\n\r\n\r\n### Suggestions\r\n\r\n#### Get Suggestions\r\n\r\nSearch and filter all suggestions using specific criteria.\r\n\r\n`GET` [Get all SKU Suggestions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions)\r\n\r\n`GET` [Get SKU Suggestion by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n\r\n#### Manage Suggestions\r\n\r\nSend or delete SKU suggestions from the seller to marketplace.\r\n\r\n`PUT` [Send SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n`DELETE` [Delete SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#delete-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n\r\n#### Get Versions\r\n\r\nSearch and filter all versions of suggestions, using specific criteria.\r\n\r\n`GET` [Get all versions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions)\r\n\r\n`GET` [Get version by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions/-version-)\r\n\r\n\r\n#### Match Received SKUs\r\n\r\nMatch SKU suggestions received in the marketplace.\r\n\r\n`PUT` [Match Received SKUs individually](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerskuid-/versions/-version-/matches/-matchid-)\r\n\r\n`PUT` [Match Multiple Received SKUs](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/matches/action/-actionName-)\r\n\r\n\r\n#### SKU Approval Settings\r\n\r\nAllows marketplaces to configure rules for automatically and manually approving SKUs received from sellers.\r\n\r\n`GET`[Get autoApprove Status in Account Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/autoapproval/toggle) \r\n\r\n`PUT`[Activate autoApprove in Marketplace's Account](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle) \r\n\r\n`GET`[Get Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration)\r\n\r\n`PUT`[Save Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration)\r\n\r\n`GET`[Get Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/seller/-sellerId-)\r\n\r\n`PUT`[Save Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/seller/-sellerId-)\r\n\r\n`PUT`[Activate autoApprove Setting for a Seller](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle/seller/-sellerId-) \r\n\r\n\r\n### Matched Offers\r\n\r\nOffers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured.\r\n\r\n`GET`[Get Matched Offers List](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/offers)\r\n\r\n`GET`[Get Matched Offer's Data by SKU ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-/sku/-skuId-) \r\n\r\n`GET`[Get Matched Offer's Data by Product ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-)\r\n", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://api.vtex.com/{accountName}", "description": "Suggestions Server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" } } } ], "paths": { "/suggestions/configuration/autoapproval/toggle": { "get": { "tags": [ "SKU approval settings" ], "summary": "Get autoApprove status in account settings", "description": "This endpoint can be used to check whether the autoapprove setting is active or not, for a specific seller. \n\nIf the response is `true`, the autoapprove setting is active. If the response is `false`, it is inactive.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetautoApprovevaluefromconfig", "parameters": [ { "name": "sellerId", "in": "query", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.", "required": true, "style": "form", "schema": { "type": "string", "example": "seller123" } }, { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "Enabled": { "type": "boolean", "description": "If the autoapprove setting is active for a given seller (`true`) or not (`false`)." } } }, "example": { "Enabled": false } } } } }, "deprecated": false }, "put": { "tags": [ "SKU approval settings" ], "summary": "Activate autoApprove in marketplace's account", "description": "This endpoint enables the autoapprove rule to a marketplace's whole Received SKUs module. Once enabling the rule, received SKUs will be automatically approved on your store, regardless of the seller. \n\n For the autoapprove rule to work as expected, the approval [Matcher score](https://help.vtex.com/en/tutorial/entendendo-a-pontuacao-do-vtex-matcher--tutorials_424) should be set up as 80 (default value), but you can configure a different number through the field `Score` in [Save Account's Approval Settings](https://developers.vtex.com/vtex-rest-api/reference/saveaccountconfig).\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveautoapproveforaccount", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "description": "The request payload that configures the autoapproval setting for a marketplace account. This JSON object must include the `Enabled` field, which determines whether the autoapproval rule should be activated (`true`) or deactivated (`false`). When enabled, all received SKUs will be automatically approved, regardless of the seller or the Matcher Score.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveautoapproveforaccountRequest" }, "example": { "Enabled": true } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "Enabled": { "type": "boolean", "description": "If the autoapprove setting is active (`true`) or not (`false`)." } } }, "example": { "Enabled": false } } } } }, "deprecated": false } }, "/suggestions/configuration": { "get": { "tags": [ "SKU approval settings" ], "summary": "Get account's approval settings", "description": "This endpoint retrieves the current approval settings of a marketplace's Received SKUs module. Its response includes: \n\n- `Score`: Matcher scores for approving and rejecting SKUs received from sellers. \n\n- `Matchers`: All Matchers configured on the marketplace, and their respective details. \n\n- `SpecificationsMapping`: Mapping of product and SKU specifications, per seller. \n\n- `MatchFlux`: This field determines the type of approval configuration applied to SKUs received from a seller. \n\nThe possible values include: \n\n-`default`, where the Matcher reviews the SKU, and approves it based on its score. \n\n-`manual`, for manual approvals through the Received SKU UI, or Match API. \n\n-`autoApprove`, for every SKU received from a given seller to be approved automatically, regardless of their Matcher Score.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getaccountconfig", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "Score": { "type": "object", "description": "Matcher scores for approving and rejecting SKUs received from sellers." }, "Matchers": { "type": "array", "description": "All Matchers configured on the marketplace, and their respective details.", "items": { "type": "object", "description": "Details of a single matcher configured in the marketplace.", "properties": { "MatcherId": { "type": "string", "description": "Identifies the matching entity, either VTEX's matcher or an external matcher." }, "hook-base-address": { "type": "string", "description": "The base address for the Matcher's API endpoint." }, "IsActive": { "type": "boolean", "description": "Indicates whether the matcher is active (`true`) or inactive (`false`)." }, "UpdatesNotificationEndpoint": { "type": "string", "description": "Endpoint for receiving notifications about updates from the matcher." }, "Description": { "type": "string", "description": "Description or notes about the matcher." } } } }, "Rules": { "type": "object", "description": "Items and products." }, "SpecificationsMapping": { "type": "array", "description": "Mapping of product and SKU specifications between the marketplace and the seller.", "items": { "type": "object", "description": "Mapping details for a single specification.", "properties": { "fieldName": { "type": "string", "description": "Name of the specification field in the seller's catalog." }, "marketplaceField": { "type": "string", "description": "Corresponding name of the specification field in the marketplace's catalog." } } } }, "MatchFlux": { "type": "string", "description": "This field determines the type of approval configuration applied to SKUs received from a seller." } } }, "example": { "Score": { "Approve": 80, "Reject": 30 }, "Matchers": [ { "MatcherId": "vtex-matcher", "hook-base-address": "http://portal.vtexinternal.com/api/ssm/hooks", "IsActive": true, "UpdatesNotificationEndpoint": "https://example.com/updates/notifications", "Description": "This matcher is configured to handle specific product categories and has been optimized for high accuracy." } ], "Rules": { "Item": [], "Product": [] }, "SpecificationsMapping": [], "MatchFlux": "Default" } } } } }, "deprecated": false }, "put": { "tags": [ "SKU approval settings" ], "summary": "Save account's approval settings", "description": "Marketplaces use this endpoint to create or update approval settings on their Received SKUs module. \n\nThe request includes all the details necessary to implement the chosen approval settings.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveaccountconfig", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "description": "The request to configure account settings, including approval thresholds, matchers, specification mappings, and approval workflows for SKUs. This JSON object should include the `Score` field to define approval and rejection scores, `Matchers` to specify approval/rejection logic, `SpecificationsMapping` to map product specifications, and `MatchFlux` to determine the approval configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveaccountconfigRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseSaveAccountsApprovalSettings" }, "example": { "Score": { "Approve": 80, "Reject": 30 }, "Matchers": [ { "MatcherId": "vtex-matcher", "hook-base-address": "http://simple-suggestion-matcher.vtex.com.br", "IsActive": true, "UpdatesNotificationEndpoint": "notification.endpoint", "Description": "Note" } ], "Rules": { "Item": [ 1 ], "Product": [ "Shirt" ] }, "SpecificationsMapping": [ { "SellerId": "Store1", "Mapping": { "Yellow": "Light yellow" } } ], "MatchFlux": "autoApprove" } } } } }, "deprecated": false } }, "/suggestions/configuration/account/config": { "get": { "tags": [ "SKU approval settings" ], "summary": "Get account's matcher settings", "description": "This endpoint will be used by the marketplace to query the matcher's current approval settings on their incoming SKUs module. If the account has no matcher configured, the response will be `404 Not Found`. \n\nFor account approval configuration information, with response including specification information, see [Get Account Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration) terminal. \n\nThe [VTEX matcher](https://help.vtex.com/pt/tutorial/entendendo-a-punctuacao-do-vtex-matcher--tutorials_424) is a tool used by marketplaces to evaluate SKUs corresponding to information from an advertisement of the seller, with those of items already present in the marketplace catalog.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getmatchconfig", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseGetAccountsMatcherSettings" }, "example": { "score": { "approve": 85, "pending": 31, "reject": 30 }, "matchers": [ { "matcherId": "example-matcher", "hook-base-address": "http://portal.vtexinternal.com.br/api/u90/hooks", "isActive": true, "updatesNotificationEndpoint": null, "description": null } ], "rules": { "item": [], "product": [] }, "specificationsMapping": [], "matchFlux": "Default" } } } } }, "deprecated": false } }, "/suggestions/configuration/seller/{sellerId}": { "get": { "tags": [ "SKU approval settings" ], "summary": "Get seller's approval settings", "description": "This endpoint retrieves the current Received SKUs approval settings applied to a specific seller. Its response includes: \n\n- `sellerId`: A string that identifies the seller in the marketplace. \n\n- `accountId`: Marketplace’s account ID. \n\n- `accountName`: Marketplace’s account name. \n\n- `mapping`: Mapping of SKU and product Specifications. \n\n- `matchFlux`: This field determines the type of approval configuration applied to SKUs received from a seller. \n\nThe possible values include: \n\n-`default`, where the Matcher reviews the SKU, and approves it based on its score. \n\n-`manual`, for manual approvals through the Received SKU UI and Match API. \n\n-`autoApprove`, for every SKU received from a given seller to be approved automatically, regardless of the Matcher Score.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n|Mapper| Suggestion resources| **Mapper**|\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getselleraccountconfig", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseGetSellersApprovalSettings" }, "example": { "sellerId": "sellerexample", "accountId": "d74dau71f-325a-4463-bd53-ae8b0453186ca", "accountName": "marketplaceexample", "mapping": { "defaultColor": "white /black", "searchColor": "color1, color2", "color1": "black", "color2": "white", "color": "black", "size": "EUR44" }, "matchFlux": "autoApprove" } } } } }, "deprecated": false }, "put": { "tags": [ "SKU approval settings" ], "summary": "Save seller's approval settings", "description": "Marketplaces use this endpoint to create or update approval settings to a specific seller, on the Received SKUs module. \n\nThe request includes all the details necessary to implement the chosen approval settings.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putselleraccountconfig", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "description": "The request for updating seller account configurations, including SKU mapping and approval workflows. This JSON object must include the `sellerId`, which uniquely identifies the seller; `mapping`, which specifies the SKU and product specifications to be mapped; and `matchFlux`, which determines the approval configuration for SKUs received from the seller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutselleraccountconfigRequest" }, "example": { "sellerId": "1a", "mapping": null, "matchFlux": "Default" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/suggestions/configuration/autoapproval/toggle/seller/{sellerId}": { "put": { "tags": [ "SKU approval settings" ], "summary": "Activate autoApprove setting for a seller", "description": "This endpoint enables the auto approve setting to received SKUs from a specific seller. Be aware that once enabling the rule through this request, all received SKUs from that seller will be automatically approved on your store, regardless of the Matcher Score.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveautoapproveforaccountseller", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "description": "The request for configuring autoapproval settings for a specific seller account. Include the `Enabled` field to activate or deactivate the autoapprove rule for the seller. When enabled, all SKUs from this seller will be automatically approved in the store, regardless of the Matcher Score.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveautoapproveforaccountsellerRequest" }, "example": { "Enabled": true } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/suggestions": { "get": { "tags": [ "Get suggestions" ], "summary": "Get all SKU suggestions", "description": "This endpoint retrieves a list of all SKUs sent by the seller for the marketplace's approval. Marketplace operators should use this endpoint whenever they want to check the full list of received SKUs and their information. \n\nNote that all the information sent by the seller will be in the [content] object. All remaining information in this endpoint's response is given by the Matcher. \n\nMatcher rates received SKUs by correlating the data sent by sellers, to existing fields in the marketplace. The calculation of these scores determines whether the product has been: \n\n`Approved`: Score equal to or greater than 80 points. \n\n`Pending`: From 31 to 79 points.\n\n`Denied`: From 0 to 30 points. \n\nNote that if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion| Suggestion resources | **Main access** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getsuggestions", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "q", "in": "query", "description": "This field allows you to customize your search. You can fill in this query param if you want to narrow down your search using the available filters on Received SKU modules.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "" } }, { "name": "type", "in": "query", "description": "This field allows users to filter SKU suggestions, by searching only the new suggestions that were just sent, and suggestions that have already been sent, but were updated. Possible values for this field include `new` and `update`.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "new" } }, { "name": "seller", "in": "query", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller so it can call this endpoint.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "" } }, { "name": "status", "in": "query", "description": "Narrow down you search, filtering by status. Values allowed on this field include: `accepted`, `pending` and `denied.`", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "accepted" } }, { "name": "hasmapping", "in": "query", "description": "This field allows you to filter SKUs that have mapping or not. Insert `true` to filter SKUs that have mapping, or `false` to retrieve SKUs that aren't mapped.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "true" } }, { "name": "matcherid", "in": "query", "description": "Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "default": "vtex-matcher" } }, { "name": "_from", "in": "query", "description": "Define your pagination range, by adding the pagination starting value. Values should be bigger than 0, with a maximum of 50 records per page.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 1 } }, { "name": "_to", "in": "query", "description": "Define your pagination range, by adding the pagination ending value. Values should be bigger than 0, with a maximum of 50 records per page.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 50 } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/suggestions/{sellerId}/{sellerSkuId}": { "put": { "tags": [ "Manage suggestions" ], "summary": "Send SKU suggestion", "description": "This request is used by the seller when it wants to suggest that one of their SKUs is sold in the marketplace.\n\nBefore using this request, the seller should always use the [Change Notification](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-seller-sku-notification) request in order to check if the SKU already exists in the marketplace. If it doesn't, then this is the next call in the SKU integration flow.\n\nIn the Send Suggestion request, the seller must send information about the SKU, such as the product and SKU name, the seller ID, and the image URL. All parameters are explained below.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Send marketplace suggestion** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "SaveSuggestion", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account to which the seller wants to suggest a new SKU. It is used as part of the request URL.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "sellerSkuId", "in": "path", "description": "A string that identifies the SKU in the seller. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } } ], "requestBody": { "description": "Object containing the details of the product suggestion to be submitted. It includes all necessary information such as product identification, dimensions, specifications, and pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveSuggestionRequest" }, "example": { "ProductId": "321", "ProductName": "Product sample", "NameComplete": "Complete product name", "ProductDescription": "sample", "BrandName": "Brand 1", "SkuName": "Sku sample", "SellerId": "string", "Height": 1, "Width": 1, "Length": 1, "Weight": 1, "Updated": null, "RefId": "REFID123", "SellerStockKeepingUnitId": 567, "CategoryFullPath": "Category 1", "Images": [ { "imageName": "Principal", "imageUrl": "https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg" } ], "ProductSpecifications": [ { "fieldName": "Fabric", "fieldValues": [ "Cotton", "Velvet" ] } ], "SkuSpecifications": [ { "fieldName": "Color", "fieldValues": [ "Red", "Blue" ] } ], "EAN": "EAN123", "MeasurementUnit": "un", "UnitMultiplier": 1, "AvailableQuantity": 111, "Pricing": { "Currency": "BRL", "SalePrice": 399, "CurrencySymbol": "R$" } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "get": { "tags": [ "Get suggestions" ], "summary": "Get SKU suggestion by ID", "description": "This endpoint retrieves the data of a specific SKU sent by the seller, to the marketplace. Marketplaces or external matchers can call this endpoint when they want to check the information about a single SKU. \n\nNote that all the information sent by the seller will be in the [content] object. All remaining information in this endpoint's response is given by the Matcher. \n\nMatcher rates received SKUs by correlating the data sent by sellers, to existing fields in the marketplace. The calculation of these scores determines whether the product has been: \n\n`Approved`: score equal to or greater than 80 points. \n\n`Pending`: from 31 to 79 points.\n\n`Denied`: from 0 to 30 points. \n\nNote that if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Send marketplace suggestion** |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion | Suggestion resources | **Main** |\r\n\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetSuggestion", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "sellerSkuId", "in": "path", "description": "A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "delete": { "tags": [ "Manage suggestions" ], "summary": "Delete SKU suggestion", "description": "This endpoint deletes a chosen SKU suggestion. Only one SKU should be deleted per request. This action cannot be undone. A workaround to revert a deletion is to send the suggestion again, through the Send Suggestion API.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion | Suggestion resources | **Main** |\r\n\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "DeleteSuggestion", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL.", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "sellerSkuId", "in": "path", "description": "A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/suggestions/{sellerId}/{sellerskuid}/versions": { "get": { "tags": [ "Get versions" ], "summary": "Get all versions", "description": "Whenever a SKU suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. \n\nThis endpoint retrieves the data of *all* previous and latest versions of a specific SKU suggestion, sent by the seller. Whenever a SKU is updated, it is important to map previous versions, to compare and identify changes. \n\nThe response's object [latestversion] provides the information of the most recent version of that SKU suggestion.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion | Suggestion resources | **Main** |\r\n\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetVersions", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "sellerskuid", "in": "path", "description": "A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/suggestions/{sellerId}/{sellerskuid}/versions/{version}": { "get": { "tags": [ "Get versions" ], "summary": "Get version by ID", "description": "Whenever a SKU suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. \n\n This endpoint retrieves a specific *version* of a chosen SKU sent by the seller. Add the Seller's ID, Seller's SKU ID, and version ID in the path to detail your search.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion | Suggestion resources | **Main** |\r\n\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetSuggestionbyversion", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "sellerskuid", "in": "path", "description": "A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } }, { "name": "version", "in": "path", "description": "Whenever an SKU Suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. This field is the `versionId` associated to the version you choose to search for. You can get this field's value through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). through the `latestVersionId` field.", "required": true, "style": "simple", "schema": { "type": "string", "example": "09072021142808277" } } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/suggestions/{sellerId}/{sellerskuid}/versions/{version}/matches/{matchid}": { "put": { "tags": [ "Match received SKUs" ], "summary": "Match received SKUs individually", "description": "All SKUs sent from a seller to a marketplace must be reviewed and matched. Actions in the matching process are added in the request body through the [matchType] object. Match type actions include: \n\n1. `newproduct`: Match the SKU as a new product. \n\n2. `itemMatch`: Associate the received SKU to an existing SKU. \n\n3. `productMatch`: Associate the received SKU to an existing product. \n\n4. `deny`: Deny the received SKU. \n\n5. `pending`: The received SKU requires attention. \n\n6. `incomplete`: The received SKU is lacking information to be matched. \n\n7. `insufficientScore`: The Score given by the Matcher to this received SKU doesn't qualify it to be matched. \n\nNote that if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion | Suggestion resources | **Main** |\r\n\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Match", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, { "name": "sellerskuid", "in": "path", "description": "A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } }, { "name": "version", "in": "path", "description": "Whenever an SKU Suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. This field is the versionId associated to the version you choose to search for. You can get this field's value through the[Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). through the `latestVersionId` field.", "required": true, "style": "simple", "schema": { "type": "string", "example": "09072021142808277" } }, { "name": "matchid", "in": "path", "description": "Whenever an SKU suggestion is matched, it is associated to a unique ID. Fill in this field with the matchId you wish to filter by. The `matchId`'s value can be obtained through the *[Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.", "required": true, "style": "simple", "schema": { "type": "string" } } ], "requestBody": { "description": "Object containing the details for matching SKUs or products. This includes the matcher ID, the score given by the matcher, the type of match to be applied, and references to existing SKUs or products if applicable. It also includes information about the product and SKU to be matched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchRequest" }, "example": { "matcherId": "{{matcherid}}", "matchType": "itemMatch", "score": "{{score}} (must be decimal)", "skuRef": "{{skuid}}(should be specifed when match is a sku match)", "productRef": "{{productRef}}(should be specified when match is a product match)", "product": { "name": "Book A", "description": "Book description", "categoryId": 12, "brandId": 1234567, "matchType": "itemMatch", "specifications": null }, "sku": { "name": "Sku exemplo", "eans": [ "12345678901213" ], "refId": null, "height": 1, "width": 1, "length": 1, "weight": 1, "images": { "imagem1.jpg": "https://imageurl.example" }, "unitMultiplier": 1, "measurementUnit": "un", "specifications": { "Packaging": "3kg" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json":{ "schema":{ "$ref":"#/components/schemas/responseMatchMultiple" }, "example": [ { "matchId": "06272023010821403", "matcherId": "vtex-matcher", "sellerId": "test858", "itemID": "81", "isSuccess": false } ] } } } }, "deprecated": false } }, "/suggestions/matches/action/{actionName}": { "put": { "tags": [ "Match received SKUs" ], "summary": "Match multiple received SKUs", "description": "Allows a marketplace to bulk approve, deny, or associate up to 25 received SKUs from sellers.\n\nThrough the `actionName` attribute, you can select the operation you want to apply to the received SKU. Actions include: \n\n* `newproduct`: Match the SKU as a new product. \n\n* `skuassociation`: Associate the received SKU to an existing SKU. \n\n* `productassociation`: Associate the received SKU to an existing product. \n\n* `deny`: Deny the received SKU.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| ---------- | ------------ | ------------ |\r\n| Channels | UI resources | **Save suggestion rules** |\r\n| Suggestion | Suggestion resources | **Main** |\r\n\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "MatchMultiple", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL", "schema": { "type": "string", "example": "apiexamples" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "actionName", "in": "path", "description": "Operation to apply to received SKUs. Possible values include: \n\n* `newproduct`: match the SKU as a new product. \n\n* `skuassociation`: associate the received SKU to an existing SKU. \n\n* `productassociation`: associate the received SKU to an existing product. \n\n* `deny`: deny the received SKU.", "required": true, "style": "simple", "schema": { "type": "string", "enum": [ "newproduct", "skuassociation", "productassociation", "deny" ], "example": "newproduct" } } ], "requestBody": { "description": "Array of objects representing multiple SKU or product match requests.", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MatchMultiple" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseMatchMultiple" }, "example": [ { "matchId": "06272023010821403", "matcherId": "vtex-matcher", "sellerId": "test858", "itemID": "81", "isSuccess": false } ] } } } }, "deprecated": false } } }, "components": { "schemas": { "SaveautoapproveforaccountRequest": { "required": [ "Enabled" ], "type": "object", "description": "Request object for configuring automatic approval settings for SKUs in an account.", "properties": { "Enabled": { "type": "boolean", "description": "Insert `true` if you wish to activate the autoapprove rule for an entire marketplace account. Insert `false` if you wish to deactivate it. Be aware that once enabling the setting through this request, all received SKUs will be automatically approved on your store, regardless of the seller, or the Matcher Score.", "example": true } } }, "SaveaccountconfigRequest": { "required": [ "Score", "Matchers", "SpecificationsMapping", "MatchFlux" ], "type": "object", "description": "Request object for saving account configuration settings.", "properties": { "Score": { "$ref": "#/components/schemas/Score" }, "Matchers": { "type": "array", "items": { "$ref": "#/components/schemas/Matcher" }, "description": "Matchers for approving and rejecting SKUs received from sellers." }, "SpecificationsMapping": { "type": "array", "description": "This attribute maps product and SKU specifications.", "items": { "type": "string", "description": "Each item in the array represents a specification that is mapped to either a product or SKU.", "example": "color=red" } }, "MatchFlux": { "type": "string", "description": "This field determines the type of approval configuration applied to SKUs received from a seller. The possible values include: \n\n- `default` where the Matcher reviews the SKU, and approves it based on its score \n\n- `manual` for manual approvals through the Received SKU UI or Match API \n\n- `autoApprove` for every SKU received from a given seller to be approved automatically, regardless of the Matcher Score.", "default": "autoApprove", "example":"autoApprove" } }, "example": { "Score": { "Approve": 80, "Reject": 30 }, "Matchers": [ { "MatcherId": "vtex-matcher", "hook-base-address": "http://simple-suggestion-matcher.vtex.com.br", "IsActive": true, "UpdatesNotificationEndpoint": null, "Description": null } ], "SpecificationsMapping": [ "color=red", "size=L" ], "MatchFlux": "autoApprove" } }, "Score": { "description": "Matcher rates received SKUs by comparing the data sent by sellers to existing fields in the marketplace. The calculation of these scores determines whether the product has been: `Approved` or `Denied`.", "required": [ "Approve", "Reject" ], "type": "object", "properties": { "Approve": { "type": "integer", "description": "Insert in this field the desired minimum score to approve SKUs. If this field is set as 99, it means all approvals will be made manually.", "format": "int32", "default":80, "example":80 }, "Reject": { "type": "integer", "description": "Insert in this field the desired maximum score to reject SKUs.", "format": "int32", "default": 30, "example":30 } } }, "Matcher": { "required": [ "MatcherId", "hook-base-address", "IsActive", "UpdatesNotificationEndpoint" ], "type": "object", "description": "Represents a matcher configuration in the marketplace.", "properties": { "MatcherId": { "type": "string", "description": "Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.", "default": "vtex-matcher", "example":"vtex-matcher" }, "hook-base-address": { "type": "string", "description": "The chosen Matcher's url. It is the endpoint that the Received SKUs module calls, to send new suggestions for the Matcher's review.", "example": "http://simple-suggestion-matcher.vtex.com.br" }, "IsActive": { "type": "boolean", "description": "Whether the matcher is active in the account (`true`), or not (`false`).", "example": true }, "UpdatesNotificationEndpoint": { "type": "string", "description": "The Received SKUs module uses this endpoint to send updates about a suggestion, to the chosen Matcher.", "nullable": true, "example": "https://example.com/notification-endpoint" }, "Description": { "type": "string", "description": "Insert in this field any notes about the approval. This field is optional.", "nullable": true, "example": "This approval is for the new product batch from supplier X." } } }, "responseGetAccountsMatcherSettings": { "description": "Response from Get Account's Matcher Settings endpoint with information about current matcher score setting, rules, spec mapping, and matchFlux.", "type": "object", "properties": { "score": { "description": "[Matcher](https://help.vtex.com/pt/tutorial/entendendo-a-pontuacao-do-vtex-matcher--tutorials_424) rates received SKUs by comparing the data sent by sellers to existing fields in the marketplace. The calculation of these scores determines whether the product has been: `Approved`, `Pending` or `Denied`.", "type": "object", "properties": { "approve": { "type": "integer", "description": "Minimum approval score set by the marketplace.", "default": 80 }, "pending": { "type": "integer", "description": "Minimum value for the ad to be pending.", "default": 31 }, "reject": { "type": "integer", "description": "Bounce score set by marketplace.", "default": 30 } } }, "matchers": { "description": "Array of objects that presents a list of matchers configured in the marketplace. If the marketplace has more than one matcher configured in the account, an array will be displayed for each matcher.\n\n By default, the VTEX Matcher is set up automatically in VTEX account.", "type": "array", "items": { "type": "object", "description": "An object representing a single matcher configuration.", "properties": { "matcherId": { "type": "string", "description": "The Matcher Id." }, "hook-base-address": { "type": "string", "description": "The base address of the Matcher hook." }, "isActive": { "type": "boolean", "description": "Indicates if Matcher is active or not. `TRUE` = Matcher is active or `FALSE` = Matcher is inactive." } } } }, "rules": { "description": "Arrays object that contains the rules defined for product approval.", "type": "object", "properties": { "item": { "type": "array", "description": "A list of rules for items.", "items": { "type": "object", "description": "A rule for items." } }, "product": { "type": "array", "description": "A list of rules for products.", "items": { "type": "object", "description": "A rule for products." } } } }, "SpecificationsMapping": { "type": "array", "description": "List of product specifications and SKU attributes configured for mapping.", "items": { "type": "object", "description": "A specification mapping entry." } }, "matchFlux": { "type": "string", "description": "This field shows what type of approval setting is being applied to SKUs received from a seller. \n\nPossible values include: \n\n-`default`: where Matcher reviews the SKU and approves it based on its score. \n\n-`manual`: for manual approvals via incoming SKU UI or mailing API. \n\n-`autoApprove`: so that every SKU received from a given seller is automatically approved, regardless of its Matcher Score." } } }, "SaveautoapproveforaccountsellerRequest": { "required": [ "Enabled" ], "type": "object", "description": "Represents a request to enable or disable automatic approval for SKUs received from a specific seller account.", "properties": { "Enabled": { "type": "boolean", "description": "Insert `true` if you wish to activate the autoapprove rule for that specific seller account. Insert `false` if you wish to deactivate it. Be aware that once enabling the setting through this request, all SKUs received from this seller will be automatically approved on your store regardless of the Matcher Score.", "default": true, "example":true } } }, "PutselleraccountconfigRequest": { "required": [ "sellerId", "mapping", "matchFlux" ], "type": "object", "description": "Represents a request to update or configure the seller account settings in the system. This configuration ensures that the seller's account is properly set up for matching and approval processes.", "properties": { "sellerId": { "type": "string", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.", "example": "seller123" }, "mapping": { "type": "object", "description": "Mapping of SKU and product Specifications. This object should be sent in the following format for all fields you wish to map:\n\n{specificationName}:{specificationValue},\n\nExample:\n\nChoose voltage: Voltage,\n\nChoose size: Size.", "nullable": true, "example": { "Choose voltage": "Voltage", "Choose size": "Size", "Choose volume": "Volume", "Choose type": "Type" } }, "matchFlux": { "type": "string", "description": "This field determines the type of approval configuration applied to SKUs received from a seller. The possible values include: \n\n- `default` where the Matcher reviews the SKU, and approves it based on its score \n\n- `manual` for manual approvals through the Received SKU UI or Match API \n\n- `autoApprove` for every SKU received from a given seller to be approved automatically, regardless of the Matcher Score.", "default": "autoApprove", "example":"autoApprove" } } }, "SaveSuggestionRequest": { "required": [ "ProductName", "ProductId", "ProductDescription", "BrandName", "SkuName", "SellerId", "Height", "Width", "Length", "Weight", "Updated", "RefId", "CategoryFullPath", "Images", "EAN", "AvailableQuantity", "Pricing" ], "type": "object", "description": "Represents a request to save or update a product suggestion in the system. This object contains all necessary details about the product and SKU.", "properties": { "ProductName": { "type": "string", "description": "Name of the suggested product. This field has a limit of 150 characters.", "example": "128GB black smartphone" }, "ProductId": { "type": "string", "description": "Product ID in seller's account.", "example": "1234" }, "ProductDescription": { "type": "string", "description": "Product description containing the main information about the product (not the SKU).", "example":"Triple camera smartphone with USB-C charger." }, "BrandName": { "type": "string", "description": "Name of the brand to which this SKU belongs. It must match the brand created in the marketplace.", "example":"Brand 1" }, "SkuName": { "type": "string", "description": "Name of the suggested SKU.", "example":"SKU sample" }, "SellerId": { "type": "string", "description": "ID of the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "example": "1" }, "Height": { "type": "integer", "format": "decimal", "description": "Height of the SKU.", "example": 10 }, "Width": { "type": "integer", "format": "decimal", "description": "Width of the SKU.", "example": 10 }, "Length": { "type": "integer", "format": "decimal", "description": "Length of the SKU.", "example": 10 }, "Weight": { "type": "integer", "format": "decimal", "description": "Weight of the SKU in grams.", "example": 100.0 }, "RefId": { "type":"string", "description":"SKU reference code. Mandotory if the EAN is not informed.", "default":"REF10", "example":"REF10" }, "EAN": { "type": "string", "description": "SKU reference code. Mandatory if the RefId is not informed.", "example": "EAN10" }, "SellerStockKeepingUnitId": { "type": "integer", "format": "int32", "description": "ID of the SKU registered in the seller.", "example":567 }, "CategoryFullPath": { "type": "string", "description": "Full path to the SKU's category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be 'Appliances/Oven'.", "example":"Category 1" }, "SkuSpecifications": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSpecification" }, "description": "Array containing the names and values of the SKU specifications." }, "ProductSpecifications": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSpecification" }, "description": "Array containing the names and values of the product specifications." }, "Images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" }, "description": "Array containing the URLs and names the SKU images." }, "MeasurementUnit": { "type": "string", "description": "Measurement unit that should be used for this SKU. If this information doesn't apply, you should use the default value `un`.", "example":"un" }, "UnitMultiplier": { "type": "integer", "format": "int32", "description": "Unit multiplier for this SKU. If this information doesn't apply, you should use the default value `1`.", "example":1 }, "AvailableQuantity": { "type": "integer", "format": "int32", "description": "The number of items currently available for sales.", "example":111 }, "Pricing": { "type": "object", "description": "Object containing pricing details, including the currency, sales price, and currency symbol.", "properties": { "Currency": { "type": "string", "description": "The currency code representing the currency in which the sales price is denominated. This code follows the ISO 4217 standard.", "example":"BRL" }, "SalePrice": { "type": "integer", "description": "The sales price of the item in the specified currency. This value represents the cost at which the item is sold and is expressed as an integer without decimal places.", "example":399 }, "CurrencySymbol": { "type": "string", "description": "The symbol representing the currency. This symbol is used in conjunction with the sales price to display the price in a readable format.", "example":"R$" } } } }, "example": { "ProductId": "321", "ProductName": "Product sample", "NameComplete": "My complete product name?", "ProductDescription": "sample", "BrandName": "Brand 1", "SkuName": "Sku sample", "SellerId": "123", "Height": 1, "Width": 1, "Length": 1, "Weight": 1, "Updated": null, "RefId": "REFID123", "SellerStockKeepingUnitId": 567, "CategoryFullPath": "Category 1", "Images": [ { "imageName": "Principal", "imageUrl": "https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg" } ], "ProductSpecifications": [ { "fieldName": "prodspec1", "fieldValues": [ "value1", "value2" ] } ], "SkuSpecifications": [ { "fieldName": "skuspec1", "fieldValues": [ "value1", "value2" ] } ], "EAN": "EAN123", "MeasurementUnit": "un", "UnitMultiplier": 1, "AvailableQuantity": 111, "Pricing": { "Currency": "BRL", "SalePrice": 399, "CurrencySymbol": "R$" } } }, "SkuSpecification": { "type": "object", "description": "Represents a specification detail for a SKU (Stock Keeping Unit).", "properties": { "fieldName": { "type": "string", "description": "Name of the SKU specification field. Example: 'Color'.", "example": "color" }, "fieldValues": { "type": "array", "items": { "type": "string", "example": "Red", "description": "Value of the SKU specification field." }, "description": "Array with values of the SKU specification field." } }, "example": { "fieldName": "Color", "fieldValues": [ "Red", "Green" ] } }, "ProductSpecification": { "type": "object", "description": "Represents a specification detail for a product. This object includes a `fieldName` which describes the type of specification (e.g., 'Fabric type') and `fieldValues` which lists the values associated with that specification (e.g., 'Cotton', 'Polyester'). This structure helps in providing detailed attributes about the product, enhancing product descriptions and searchability.", "properties": { "fieldName": { "type": "string", "description": "Name of the product specification field.", "example": "Fabric type" }, "fieldValues": { "type": "array", "description": "Value of the product specification field.", "items": { "type": "string", "example": "Cotton", "description": "Value of the product specification field." } } }, "example": { "fieldName": "Fabric type", "fieldValues": [ "Cotton", "Polyester" ] } }, "Image": { "required": [ "imageName", "imageUrl" ], "type": "object", "description": "Represents an image associated with a product or SKU.", "properties": { "imageName": { "type": "string", "description": "Name of the SKU image.", "example":"Principal" }, "imageUrl": { "type": "string", "description": "URL of the SKU image. The image must be sent through `https` protocol, otherwise it will not be rendered in VTEX Admin.", "example": "https://imageurl.example" } }, "example": { "imageName": "Principal", "imageUrl": "https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg" } }, "MatchRequest": { "required": [ "matcherId", "score", "matchType" ], "type": "object", "description":"Represents a request for matching a SKU suggestion with existing products or SKUs. This object includes details such as the identifier of the matcher used, the score assigned to the suggestion, and the type of match action to be performed. The match type determines how the SKU should be handled, whether as a new product, an item match, or other specified actions.", "properties": { "matcherId": { "type": "string", "description": "Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.", "default": "vtex-matcher", "example":"vtex-matcher" }, "matchType": { "type": "string", "description": "Define the action you want to apply to each SKU. Values include: \n\n1. `newproduct`: match the SKU as a new product. \n\n2. `itemMatch`: associate the received SKU to an existing SKU. \n\n3. `productMatch`: associate the received SKU to an existing product. \n\n4. `deny`: deny the received SKU. \n\n5. `pending`: the received SKU requires attention. \n\n6. `incomplete`: the received SKU is lacking information to be matched. \n\n7. `insufficientScore`: the score given by the Matcher to this received SKU doesn't qualify it to be matched. \n\nNote that if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.", "example": "itemMatch" }, "score": { "type": "string", "description": "Matcher rates received SKUs by correlating the data sent by sellers, to existing fields in the marketplace. The calculation of these scores determines whether the product has been: \n\n`Approved`: score equal to or greater than 80 points. \n\n`Pending`: from 31 to 79 points.\n\n`Denied`: from 0 to 30 points. \n\nNote that if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.", "default": "80", "example":"80" }, "skuRef": { "type": "string", "nullable": true, "description": "In `itemMatch` actions, fill in this field on your request to match the item to an existing SKU in the marketplace.", "example": "12345-sku" }, "productRef": { "type": "string", "description": "In `productMatch` actions, fill in this field on your request to match the item to an existing product in the marketplace.", "example": "67890-product", "nullable": true }, "product": { "$ref": "#/components/schemas/Product" }, "sku": { "$ref": "#/components/schemas/Sku" } }, "example": { "matcherId": "vtex-matcher", "score": "80", "matchType": "itemMatch", "skuRef": "12345-sku", "productRef": "67890-product", "product": { "name": "Product exemple", "description": "Descricption exemple", "categoryId": 12, "brandId": 1234567, "specifications": null }, "sku": { "name": "Sku exemple", "eans": [ "12345678901213" ], "refId": null, "height": 1, "width": 1, "length": 1, "weight": 1, "images":{ "image1.jpg": "imageurl.example" }, "unitMultiplier": 1, "measurementUnit": "un", "specifications": { "Packaging": "3 kg" } } } }, "Product": { "required": [ "name", "description", "categoryId", "brandId", "specifications" ], "type": "object", "description":"Represents the product details in the catalog. The product object includes essential attributes such as the product's name, description, category, brand, and specifications. This information is used to define and manage the product within the marketplace, ensuring that it is properly categorized and described for users.", "properties": { "name": { "type": "string", "description": "Name of the product that will be matched.", "example": "Book" }, "description": { "type": "string", "description": "Product's description.", "example": "A fascinating book about science and technology." }, "categoryId": { "type": "integer", "format": "int32", "description": "Marketplace's Category ID that the product belongs to, configured in the Catalog. It should be the category chosen for the received SKU to be matched with. The `categoryId` is already mapped through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). You can choose to keep the same suggested `categoryID`, or overwrite it with another value in this request. This field is nulled when the inserted value is 0.", "example": 12 }, "brandId": { "type": "integer", "format": "int32", "description": "Marketplace's Brand ID that the product belongs to, configured in the Catalog. It should be the brand chosen for the received SKU to be matched with. The brandId is already mapped through the Get Suggestions API. This field is nulled when the inserted value is 0.", "example": 1234567 }, "specifications": { "type": "object", "description": "This field is optional. Add here any product specifications or details.", "nullable": true, "example":{} } } }, "Sku": { "required": [ "name", "eans", "refId", "height", "width", "length", "weight", "images", "unitMultiplier", "measurementUnit", "specifications" ], "type": "object", "description":"Represents the SKU (Stock Keeping Unit) details for a product. The SKU is a unique identifier that contains specific attributes such as dimensions, weight, and other product specific information. This object is crucial for defining and managing the individual variations of a product in the catalog.", "properties": { "name": { "type": "string", "description": "The name or title of the SKU.", "example": "128GB black smartphone" }, "eans": { "type": "array", "description": "An array of strings representing the EAN (European Article Number) codes associated with the SKU. EAN codes are unique identifiers used for products.", "items": { "type": "string", "description": "A single EAN code for the SKU. This is a numeric string typically consisting of 13 digits.", "example": "12345678901213" }, "example": [ "1234567901213" ], "nullable": true }, "refId": { "type": "string", "description": "SKU reference code.", "example": "1234", "nullable": true }, "height": { "type": "integer", "format": "int32", "description": "Height of the SKU.", "example": 10 }, "width": { "type": "integer", "format": "int32", "description": "Width of the SKU.", "example": 20 }, "length": { "type": "integer", "format": "int32", "description": "Length of the SKU.", "example": 10 }, "weight": { "type": "integer", "format": "int32", "description": "Weight of the SKU.", "example": 100 }, "images": { "$ref": "#/components/schemas/Images" }, "unitMultiplier": { "type": "integer", "format": "int32", "description": "Unit multiplier for this SKU. If this information doesn't apply, you should use the default value 1.", "default": 1, "example": 3 }, "measurementUnit": { "type": "string", "description": "Measurement unit that should be used for this SKU. If this information doesn't apply, you should use the default value un.", "default": "un", "nullable": true, "example":"un" }, "specifications": { "$ref": "#/components/schemas/Specifications" } }, "example": { "name": "Sku exemplo", "eans": [ "12345678901213" ], "refId": null, "height": 1, "width": 1, "length": 1, "weight": 1, "images": { "imagem1.jpg": "imageurl.example" }, "unitMultiplier": 3, "measurementUnit": "un", "specifications": { "Packaging": "3 kg" } } }, "Images": { "type": "object", "description": "An object that represents a single SKU image with a filename as the key and the image URL as the value.", "properties": { "imagem1.jpg": { "type": "string", "description": "The URL of the SKU's image. Must be an `https` URL.", "example": "https://imageurl.example" } } }, "Specifications": { "required": [ "Packaging" ], "type": "object", "description": "Object representing the specifications of a product, including details related to its packaging and other relevant attributes.", "properties": { "Packaging": { "type": "string", "description": "Packaging specifications. Should include package's weight.", "example":"3kg" } } }, "MatchMultiple": { "type": "array", "description":"An array containing multiple match operations, each represented as an object. This array allows for the processing of multiple SKU suggestions in a single request.", "items": { "type": "object", "description":"Represents a single match operation for a SKU suggestion, including details such as item ID, version ID, match ID, category, and seller information.", "required": [ "itemId", "versionId", "matchId", "matcherId", "categoryId", "sellerId" ], "properties": { "itemId": { "type": "string", "description": "This field can be used to link any string that identifies that SKU. Its most common use is the seller's SKU ID.", "example": "1234567" }, "versionId": { "type": "string", "description": "Whenever an SKU Suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. This field is the `versionId` associated to the version you choose to search for. You can get this field's value through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). through the `latestVersionId` field.", "example": "v.2" }, "matchId": { "type": "string", "description": "Whenever an SKU suggestion is matched, it is associated to a unique ID. Fill in this field with the `matchId` you wish to filter by. The `matchId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.", "default": "vtex-matcher", "example":"vtex-matcher" }, "matcherId": { "type": "string", "description": "Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.", "default":"vtex-matcher", "example":"vtex-matcher" }, "categoryId": { "type": "integer", "format": "int32", "nullable": true, "description": "Marketplace's Category ID that the product belongs to, configured in the Catalog. It should be the category chosen for the received SKU to be matched with. The `categoryId` is already mapped through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). You can choose to keep the same suggested `categoryID`, or overwrite it with another value in this request. This field is nulled when the inserted value is 0.", "example": 12 }, "brandId": { "type": "integer", "format": "int32", "nullable": true, "description": "Marketplace's Brand ID that the product belongs to, configured in the Catalog. It should be the brand chosen for the received SKU to be matched with. The `brandId` is already mapped through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). This field is nulled when the inserted value is 0, and is mandatory for the `newproduct` action.", "example": 1234567 }, "skuRef": { "type": "string", "nullable": true, "description": "Fill in this field on your request when the matched item is an SKU. This field is mandatory for the `skuassociation` action.", "example": "123 sku ref" }, "productRef": { "type": "string", "description": "Fill in this field on your request when the matched item is a product. This field is mandatory for the `productassociation` action.", "example": "123 product ref", "nullable": true }, "sellerId": { "type": "string", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "example": "seller123" } } } }, "responseMatchMultiple": { "type": "array", "description":"An array containing the results of multiple match operations. Each object in the array represents the outcome of a single match attempt.", "items": { "type": "object", "description":"Represents the result of a single match operation, including details such as match ID, matcher ID, seller ID, item ID, and whether the operation was successful.", "properties": { "matchId": { "type": "string", "description":"Unique identifier for the match operation, which can be used for tracking and auditing purposes." }, "matcherId": { "type": "string", "description":"Identifier for the matcher entity that performed the match. It can represent VTEX's internal matcher or an external matcher service." }, "sellerId": { "type": "string", "description":"Unique identifier of the seller who owns the SKU being matched." }, "itemId": { "type": "string", "description": "Unique identifier of the item (SKU) that was processed during the match operation." }, "isSuccess": { "type": "boolean", "description": "Indicates whether the match operation was successful. A value of `true` means the operation succeeded, while `false` indicates a failure." } } } }, "responseGetSellersApprovalSettings": { "type": "object", "description":"Represents the approval settings configured for a specific seller within the marketplace. This object includes details about the seller, their account, and how SKUs are mapped and approved.", "properties": { "sellerId": { "type": "string", "description": "A string that identifies the seller in the marketplace." }, "accountId": { "type": "string", "description": "Marketplace’s account ID." }, "accountName": { "type": "string", "description": "Marketplace’s account name." }, "mapping": { "type": "object", "default": {}, "description": "SKU mapping information and product [specifications](https://developers.vtex.com/docs/guides/catalog-overview#configuring-initial-settings-mandatory).\n\n The properties included within `mapping` can change according to the product type, the `color` specification and its variations described in this example are just one of the possibilities. The values received in this call's payload for those properties depend on the seller's catalog architecture, and are not default. \n\nSee some examples of specifications: \n\n- Voltage \n\n- Power \n\n- Size \n\n- Height \n\n- Width.", "properties": { "defaultColor": { "type": "string", "description": "The field will indicate the default color predefined by the seller in cases where specific product colors are not defined. This field is neither mandatory nor default, it will depend on the architecture of the seller's catalog." }, "searchColor": { "type": "string", "description": "Field that provides the available colors to filter searches. This field is neither mandatory nor default, it will depend on the architecture of the seller's catalog." }, "color1": { "type": "string", "description": "`color1` available for search filter. This field is neither mandatory nor default, it will depend on the architecture of the seller's catalog." }, "color2": { "type": "string", "description": "`color2` available for search filter. This field is neither mandatory nor default, it will depend on the architecture of the seller's catalog." }, "color": { "type": "string", "description": "Indicates the predominant or main color of the product. This field is neither mandatory nor default, it will depend on the architecture of the seller's catalog." }, "size": { "type": "string", "description": "Indicates the size of the product. This field is neither mandatory nor default, it will depend on the architecture of the seller's catalog." } } }, "matchFlux": { "type": "string", "description": "This field determines the type of [approval configuration applied to SKUs received from a seller](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/seller/-sellerId-). \n\nThe possible values include: \n\n-`default`, where the Matcher reviews the SKU, and approves it based on its score. \n\n-`manual`, for manual approvals through the Received SKU UI and Match API. \n\n-`autoApprove`, for every SKU received from a given seller to be approved automatically, regardless of the Matcher Score." } } }, "responseSaveAccountsApprovalSettings": { "type": "object", "description": "Response object for the Save Accounts Approval Settings endpoint.", "properties": { "Score": { "type": "object", "description": "[Matcher's rates](https://help.vtex.com/en/tutorial/understanding-vtex-matcher-scoring) to approve or reject [received SKUs](https://help.vtex.com/en/tutorial/cataloging-received-skus--tutorials_396) sent by sellers.", "properties": { "Approve": { "type": "integer", "description": "Score to approve SKUs sent by sellers." }, "Reject": { "type": "integer", "description": "Score to reject SKUs sent by sellers." } } }, "Matchers": { "type": "array", "description": "[Matchers](https://help.vtex.com/en/tutorial/understanding-vtex-matcher-scoring) configurations for approving and rejecting [received SKUs](https://help.vtex.com/en/tutorial/cataloging-received-skus--tutorials_396) sent by sellers.", "items": { "type":"object", "description": "Details of a matcher used for scoring and managing SKUs approvals and rejections.", "properties": { "MatcherId": { "type": "string", "description": "Identifies the matching entity. It can be either [VTEX's matcher](https://help.vtex.com/en/tutorial/understanding-vtex-matcher-scoring), or an external matcher." }, "hook-base-address": { "type": "string", "description": "The given matcher's URL." }, "IsActive": { "type": "boolean", "description": "Whether the matcher is active in the account (`true`), or not (`false`)." }, "UpdatesNotificationEndpoint": { "type": "string", "description": "The [received SKUs](https://help.vtex.com/en/tutorial/cataloging-received-skus--tutorials_396) module calls this endpoint for matcher's suggestions updates." }, "Description": { "type": "string", "description": "The note inserted on the request body." } } } }, "Rules": { "type": "object", "description": "Items and products that belong to sellers.", "properties": { "Item": { "type": "array", "description": "SKUs' ID.", "items": { "type": "integer", "description": "SKU ID." } }, "Product": { "type": "array", "description": "Product's name.", "items": { "type": "string", "description": "Product name." } } } }, "SpecificationsMapping": { "type": "array", "description": "This attribute maps product and SKU's specifications between the marketplace and the seller.", "items": { "type": "object", "description": "Object representing a single specification mapping between the marketplace and the seller.", "properties": { "SellerId": { "type": "string", "description": "The seller ID." }, "Mapping": { "type": "object", "description": "The attributes and values mapped between the marketplace and the seller." } } } }, "MatchFlux": { "type": "string", "description": "Type of approval configuration that apply to received SKUs sent by sellers. The possible values are: \n\n`default`: The matcher approves the SKU. \n\n`manual`: Manual SKU's approvals. \n\n`AutoApprove`: Automatic SKU's approvals." } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" } } }, "tags": [ { "name": "Get suggestions", "description": "Search and filter all suggestions using specific criteria." }, { "name": "Manage suggestions", "description": "Send or delete SKU suggestions from the seller to marketplace." }, { "name": "Get versions", "description": "Search and filter all versions of suggestions, using specific criteria." }, { "name": "SKU approval settings" }, { "name": "Match received SKUs", "description": "Match SKU suggestions received in the marketplace." } ] }